Sessions

Introduction

The Sessions API provides insights into user interactions with your content, tracking reading sessions and engagement metrics. This feature allows you to retrieve detailed session data, including reading duration and page changes. This section will help you understand how to leverage session data to enhance user experience and content strategy.

warning

Not available by default in all plans. Contact [email protected] for more information about this endpoint.

info

Make sure you generated the api_token on your store. More info HERE

Retrieve

GET /integration-api/v1/consumption/sessions

Query Parameters

Parameter	Type	Example
cursor	string	/integration-api/v1/consumption/sessions?cursor=eyJzdGF....J1ZX0
issue_id	integer	/integration-api/v1/consumption/sessions?issue_id=1125899910000160
user_id	integer	/integration-api/v1/consumption/sessions?user_id=1125899911002602
reason_type	string	/integration-api/v1/consumption/sessions?reason_type=free_issue
reason_value	integer	/integration-api/v1/consumption/sessions?reason_type=subscription_with_collectionsreason_value=3357
from_date	string	/integration-api/v1/consumption/sessions?from_date=2022-09-21&to_date=2022-09-23
to_date	string	/integration-api/v1/consumption/sessions?to_date=2022-09-23&to_date=2022-09-23

tip

Query parameters can be combined to achieve more specific filtering. All are optional, except the from_date and to_date fields which always go together, just as to send a reason_value you must specify reason_type.

tip

The cursor parameter can be used to paginate results.

Response

Code	Description
200	Success
403	Feature disabled for your store
401	Unauthenticated

{
    "CODE": "success",
    "current_page": 1,
    "data": [
        {
            "uuid": "151:8000005:9000886:1734446548",
            "issue_id": 8000005,
            "user_id": 9000886,
            "client_type": "browser",
            "reason_type": "assigned_issue",
            "reason_value": null,
            "seconds_reading": 125,
            "started_at": "2024-12-17 14:42:28",
            "page_changes": 12,
            "last_heartbeat_at": null,
            "user_email": "[email protected]"
        }
    ],
    "path": "https://example.publica.la/integration-api/v1/consumption/sessions",
    "per_page": 25,
    "next_cursor": "eyJzdGFydGVkX2F0IjoiMjAyNC0wOS0xOCAxNjoxMzoxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "next_page_url": "https://example.publica.la/integration-api/v1/consumption/sessions?cursor=eyJzdGFydGVkX2F0IjoiMjAyNC0wOS0xOCAxNjoxMzoxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
    "prev_cursor": null,
    "prev_page_url": null
}

The response is paginated with up to 25 sessions per page. Each session includes the following fields:

Field	Type	Description
uuid	string	Unique identifier for the session, combining tenant_id, issue_id, user_id, and timestamp.
issue_id	integer	ID of the edition associated with the session.
user_id	integer/null	ID of the user in the system. Null for guest.
user_email	string	Email of the user.
client_type	string	Platform where the session occurred. Possible values: app, browser.
reason_type	string	Reason the user accessed the content. Possible values are detailed below.
reason_value	integer/null	Additional data related to the reason, such as subscription plan ID for certain types.
started_at	datetime	Timestamp when the session started.
seconds_reading	integer	Duration of the session in seconds.
page_changes	integer	Number of page changes during the session.
last_heartbeat_at	datetime	Timestamp of the last activity ping in the session.

Possible reason_type Values

Value	Description
license_retail	Content accessed through a retail license.
administrator_user	Content accessed by an administrator.
free_issue	Content accessed because it is free.
preview_issue	Content preview access enabled.
free_access	Content accessed via integration with free access enabled.
bought_issue	Content purchased by the user.
assigned_issue	Content assigned manually by an administrator.
gifted_issue	Content gifted to the user.
external_permissions	Access through integration of reading permissions.
subscription_with_collections	Access through a subscription with content collections.
global_subscription	Access through a subscription granting global content access.
lti_and_entry_point_free_access	Access through LTI integration.
saml_and_entry_point_free_access	Access through SAML integration.

In cases where reason_type is subscription_with_collections or global_subscription, reason_value will contain the subscription plan ID.

info

The plan id can be found HERE